Skip to main content

Getting Started

This guide walks you through the minimum steps required to parse your first e-receipt using the BlinkReceipt E-Receipt API.

Prerequisites​

  • An active BlinkReceipt API key
  • A publicly reachable HTTPS endpoint to receive webhook results
  • A raw EML file from a supported retailer

Step 1: Configure Your Results Endpoint​

Before creating any jobs, tell the API where to deliver parsed results. You must configure at least a results_endpoint.

curl -X POST https://api.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "results_endpoint": "https://your-server.com/webhooks/ereceipts",
    "day_cutoff": 14
  }'

Response: the stored configuration.

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts",
  "return_eml": false,
  "default_retailer_country_list": [],
  "enable_pii_scrubbing": false,
  "use_only_retailer_emails": false,
  "date_cutoff": null,
  "date_cutoff_iso": null,
  "day_cutoff": 14,
  "retailers": []
}

See configuration.md for all available configuration fields.

Step 2: Set Your Retailers (Optional)​

If you want per-retailer cutoff windows that differ from your global setting, include them in your configuration.

A POST replaces your whole configuration, so send every field you want to keep — not only the ones you are changing. The retailers array replaces your stored retailer list outright.

curl -X POST https://api.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "results_endpoint": "https://your-server.com/webhooks/ereceipts",
    "day_cutoff": 30,
    "retailers": [
      { "email": "auto-confirm@amazon.com", "day_cutoff": 7 },
      { "email": "noreply@ebay.com", "day_cutoff": 14 }
    ]
  }'

Step 3: Create a Job​

Submit an EML email for parsing. The eml_data field contains the base64-encoded raw EML content. The email_hash field is the SHA-256 hash of the user's email address.

curl -X POST https://api.blinkreceipt.com/ereceipts/create_job \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eml_data": "UmVjZWl2ZWQ6IGZyb20...",
    "email_hash": "abc123def456...",
    "client_user_id": "user_789"
  }'

Response:

{
  "success": true,
  "job_id": 98765
}

Save the job_id — you will use it to check the job status.

To scrape a mailbox instead of a single email, pass credentials and provider rather than eml_data. See endpoints.md for the supported providers.

Step 4: Poll for Job Status​

Check whether the job has finished processing.

curl "https://api.blinkreceipt.com/ereceipts/status?job_id=98765" \
  -H "api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "job_status": {
    "id": 98765,
    "email_hash": "abc123def456...",
    "client_user_id": "user_789",
    "status": "completed",
    "error_code": null,
    "error_message": null,
    "processing_time": 3.2,
    "created_at": "2024-08-01 10:00:00",
    "updated_at": "2024-08-01 10:00:03"
  }
}

The status field cycles through: queued → executing → completed (or error).

Step 5: Receive Results at Your Webhook​

Once the job completes, the API POSTs results to your configured results_endpoint. Results are paged, and each page arrives as a separate POST. Use pageNumber and totalPages to tell when you have received everything.

{
  "jobId": "98765",
  "clientUserId": "user_789",
  "clientEmailHash": "abc123def456...",
  "pageNumber": 1,
  "totalPages": 1,
  "results": [
    {
      "blinkReceiptId": "85n24efb-6ca3-532m-9170-9410d9e7e",
      "ereceiptEmailId": "<msg-id@mail.gmail.com>",
      "emailTimestamp": "2024-08-01 09:55",
      "merchantName": { "value": "Amazon", "confidence": 100 },
      "total": { "value": 59.99, "confidence": 100 },
      "products": [
        {
          "productName": "Wireless Mouse",
          "brand": "Logitech",
          "unitPrice": { "value": 59.99, "confidence": 100 },
          "quantity": { "value": 1, "confidence": 100 }
        }
      ]
    }
  ]
}

A job that finds nothing still delivers one page with an empty results array.

For the full receipt schema, see response-structure.md.

See endpoints.md for the complete endpoint reference and error-handling.md for a full list of error codes.